home *** CD-ROM | disk | FTP | other *** search
/ AGA Toolkit '97 / The AGA Toolkit '97.iso / miscellaneous / help / dos / dosman / man / requestfile < prev    next >
Encoding:
Text File  |  1996-09-07  |  5.8 KB  |  148 lines
  1.  
  2.  
  3.         REQUESTFILE (3.x only) (Location in C:)
  4.  
  5.    NAME
  6.             Requestfile - To allow the use of the standard ASL 
  7.         file requestor in an AmigaDos or AREXX script. The ASL 
  8.         requestor is the interactive window that displays a list 
  9.         of filenames and directories and lets the user chose one.
  10.  
  11.    SYNOPSIS
  12.         REQUESTFILE [DRAWER DIR] [FILE filename] [PATTERN pat]
  13.                     [TITLE titletext] [POSITIVE postext]
  14.                     [NEGATIVE negtext] [ACCEPTPATTERN pat]
  15.                     [REJECTPATTERN pat] [SAVEMODE] [DRAWERSONLY]
  16.                     [MULTISELECT] [NOICONS] [PUBSCREEN screenname]
  17.  
  18.  
  19.    DESCRIPTION
  20.             After the user selects the file, the name of the file 
  21.         chosen is returned, surrounded by double quotes.  If 
  22.         multiple files are selected, each file is printed to the 
  23.         console seperated by spaces and exits the file requestor 
  24.         with a return code of zero. If 'CANCEL' or the close 
  25.         gadget is chosen, the program ends with a return code of 
  26.         5. The return code 5 can be detected if the "IF WARN" 
  27.         statement is used. 
  28.  
  29.    KEYWORDS
  30.             Even though there seems to be many of these, all of 
  31.         them are optional. If you issue the REQUESTFILE command 
  32.         without any keywords, a standard ASL requestor will open 
  33.         up that any user can figure out.
  34.  
  35.      DRAWER dir
  36.             The first directory listing will be the specified 
  37.         'dir', and this path will appear in the drawer gadget of 
  38.         the file requestor.
  39.  
  40.      FILE filename
  41.             The 'filename' will be the selected default file. If 
  42.         this file is not in the root directory, you must use the 
  43.         DRAWER keyword to specify its directory.
  44.  
  45.      PATTERN pat
  46.             This keyword causes only the files which match that 
  47.         pattern you specify to show up. The user can, however, 
  48.         enter any file he desires by simply entering the filename 
  49.         or by changing the pattern. If you wish the user to not 
  50.         be allowed to change the file pattern then use the 
  51.         ACCEPTPATTERN keyword instead.
  52.  
  53.      TITLE titletext
  54.             This allows you to enter the text string that will 
  55.         appear in the title bar of the window. This should be 
  56.         limited to 30 characters because anything text over 30 
  57.         letters will be cut off by the edge of the requestor. It 
  58.         is also a good idea for this text to hint the user on 
  59.         what file he should select.
  60.  
  61.      POSITIVE postext
  62.             This lets you change the button text on the leftmost 
  63.         button. The function of that button always allows the 
  64.         user to select that file. The default is labeled 'OK'. 
  65.         For instance, let's say you wanted to load that file, you 
  66.         could name that button 'Load'. Or, if you wanted to 
  67.         delete that file you could name that button 'Delete'.
  68.  
  69.      NEGATIVE negtext
  70.             This lets you change the text of the rightmost 
  71.         button, which is defaultly named 'CANCEL'. You could 
  72.         change the name to something more meaningful, such as 
  73.         'Skip' or 'Abort'.
  74.  
  75.      ACCEPTPATTERN pat
  76.             Allows you to limit the file display to those 
  77.         filenames which match the pattern you specify. This 
  78.         keyword does not give the user a chance to change the 
  79.         pattern. If you want to leave the user that flexibility, 
  80.         you should use the PATTERN keyword instead. For instance, 
  81.         if you specify 'pat' as "#?.info", the user will only be 
  82.         allowed to enter or select icons and only icons will be
  83.         displayed.
  84.  
  85.      REJECTPATTERN pat
  86.             This lets you exluce from the display all the files 
  87.         that match the pattern you specify. This is the opposite 
  88.         of ACCEPTPATTERN. Like ACCEPTPATTERN, there is no way for 
  89.         the user to change the pattern.  For instance, if 'pat' 
  90.         is "#?.info" then there is absolutly no chance for the 
  91.         user to select an icon or for one to be displayed.
  92.  
  93.      SAVEMODE
  94.             This is where the user is presented with a display 
  95.         window that is black with grey letters instead of the 
  96.         gray and black letters, and the multiselect option is 
  97.         disabled.
  98.  
  99.      DRAWERSONLY
  100.             Will not show any filenames, only the directory 
  101.         names.
  102.  
  103.      MULTISELECT
  104.             Lets the user select multiple files by holding down 
  105.         the shift key and clicking on as many files as they want. 
  106.         These files will be outputed to the console device, 
  107.         seperated by spaces, when the 'OK' button is selected.
  108.  
  109.      NOICONS
  110.             This will keep the icon files from showing up in the 
  111.         file reqestor. This can also be accomplished by using the 
  112.         "REJECTPATTERN #?.info" keyword statement.
  113.  
  114.      PUBSCREEN screenname
  115.             This is where you can chose which screen you want the 
  116.         requestor to show up on. 
  117.  
  118.  
  119.  
  120.      EXAMPLES:
  121.  
  122.             1. To have the user select a directory within a 
  123.         script, and to store that directory in the local 
  124.         environment variable dirname:
  125.  
  126.  
  127.       UNSET dirname
  128.       SET dirname 'REQUESTFILE DRAWERSONLY'
  129.       IF "$dirname" EQ "*$dirname"
  130.       ECHO "You didn't choose a directory name"
  131.       ELSE
  132.       ECHO "The directory you chose was $dirname"
  133.       ENDIF
  134.       UNSET dirname
  135.  
  136.             The Cancel button is tested for by checking for the 
  137.         "$dirname" (which is replaced by the contents of the 
  138.         environment variable) is equal to the literal string 
  139.         "$dirname". The asterisk means that the IF command will 
  140.         interpret the dollar sign as a dollar sign, not as the 
  141.         contents of an environment variable. You could not use 
  142.         the IF WARN test because you only get the return code 
  143.         from the SET command, not the REQUESTFILE command this it 
  144.         contains.
  145.  
  146.  
  147.  
  148.